<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Runtime Documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '#',
        VERSION:     '1.0',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="None" href="index.html" />
    <link rel="next" title="Services Documentation" href="services.html" />
    <link rel="prev" title="Package Documentation" href="package.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="services.html" title="Services Documentation"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="package.html" title="Package Documentation"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Index</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="runtime-documentation">
<h1>Runtime Documentation</h1>
<p>This page contains the Runtime Package documentation.</p>
<div class="section" id="module-runtime.boot">
<h2>The <tt class="xref docutils literal"><span class="pre">boot</span></tt> Module</h2>
<p>Created on 31/07/2009</p>
<p>&#64;author: Edward Huynh, Tony Allan</p>
<dl class="exception">
<dt id="runtime.boot.BadYarraPackageException">
<em class="property">exception </em><tt class="descclassname">runtime.boot.</tt><tt class="descname">BadYarraPackageException</tt></dt>
<dd>Bases: <tt class="xref docutils literal"><span class="pre">exceptions.Exception</span></tt></dd></dl>

<dl class="class">
<dt id="runtime.boot.MetaFinder">
<em class="property">class </em><tt class="descclassname">runtime.boot.</tt><tt class="descname">MetaFinder</tt></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<p>MetaFinder plays the role of the finder in the Importer Protocol.</p>
<dl class="method">
<dt id="runtime.boot.MetaFinder.find_module">
<tt class="descname">find_module</tt><big>(</big><em>fullname</em>, <em>path=None</em><big>)</big></dt>
<dd>returns a MetaLoader instance if the module is found in the datastore, otherwise None.
When None is returned, the import is of the module is delegated to the built in import function.</dd></dl>

</dd></dl>

<dl class="class">
<dt id="runtime.boot.MetaLoader">
<em class="property">class </em><tt class="descclassname">runtime.boot.</tt><tt class="descname">MetaLoader</tt><big>(</big><em>resource_id</em>, <em>metadata_key</em><big>)</big></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<p>MetaLoader plays the role of the loader in the Importer Protocol</p>
<dl class="method">
<dt id="runtime.boot.MetaLoader.load_module">
<tt class="descname">load_module</tt><big>(</big><em>module_path</em><big>)</big></dt>
<dd>returns the module specified by the module_path</dd></dl>

</dd></dl>

<dl class="exception">
<dt id="runtime.boot.XMLFormatException">
<em class="property">exception </em><tt class="descclassname">runtime.boot.</tt><tt class="descname">XMLFormatException</tt></dt>
<dd>Bases: <tt class="xref docutils literal"><span class="pre">exceptions.Exception</span></tt></dd></dl>

<dl class="function">
<dt id="runtime.boot.create_module">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">create_module</tt><big>(</big><em>module_name</em><big>)</big></dt>
<dd>returns the module created</dd></dl>

<dl class="function">
<dt id="runtime.boot.download_file">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">download_file</tt><big>(</big><em>url</em><big>)</big></dt>
<dd>returns the file located at the url provided</dd></dl>

<dl class="function">
<dt id="runtime.boot.first_time">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">first_time</tt><big>(</big><em>file_repository_location</em>, <em>distribution_name</em><big>)</big></dt>
<dd>code to run the first time this application starts up</dd></dl>

<dl class="function">
<dt id="runtime.boot.get_first_item_of_serialised_resource">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">get_first_item_of_serialised_resource</tt><big>(</big><em>serialised_resource</em><big>)</big></dt>
<dd>returns the first item in the serialised resource</dd></dl>

<dl class="function">
<dt id="runtime.boot.get_rt_module">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">get_rt_module</tt><big>(</big><big>)</big></dt>
<dd>get a reference to the rt module in the runtime package</dd></dl>

<dl class="function">
<dt id="runtime.boot.get_startup_module_names">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">get_startup_module_names</tt><big>(</big><em>configuration_xml_root_element</em><big>)</big></dt>
<dd>returns a list of all the module names that are required for startup in the manifest</dd></dl>

<dl class="function">
<dt id="runtime.boot.get_startup_modules_content">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">get_startup_modules_content</tt><big>(</big><em>package_location</em>, <em>package_digest</em><big>)</big></dt>
<dd>returns the contents of the startup modules in the package in a list with the format (file_name,content)</dd></dl>

<dl class="function">
<dt id="runtime.boot.get_zip_content">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">get_zip_content</tt><big>(</big><em>zip</em>, <em>file_name</em>, <em>encoded=True</em><big>)</big></dt>
<dd>return the contents of a file that is in a yarra package</dd></dl>

<dl class="function">
<dt id="runtime.boot.is_first_time">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">is_first_time</tt><big>(</big><big>)</big></dt>
<dd>returns True if this is the first run of the application</dd></dl>

<dl class="function">
<dt id="runtime.boot.load_distribution">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">load_distribution</tt><big>(</big><em>file_repository_location</em>, <em>distribution_name</em>, <em>load_only_boot_modules=False</em><big>)</big></dt>
<dd><p>Loads the distribution named distribution_name at the distribution 
repository location specified by file_repository_location.</p>
<p>file_repository_location and distribution name are both strings.</p>
<p>load_only_boot_modules is a flag to specify that only modules marked as &#8216;boot&#8217; are loaded.</p>
</dd></dl>

<dl class="function">
<dt id="runtime.boot.load_module">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">load_module</tt><big>(</big><em>module_name</em>, <em>module_code</em><big>)</big></dt>
<dd>creates a module named module_name and loads the module_code into that module</dd></dl>

<dl class="function">
<dt id="runtime.boot.load_package">
<tt class="descclassname">runtime.boot.</tt><tt class="descname">load_package</tt><big>(</big><em>package_name</em>, <em>package_contents</em><big>)</big></dt>
<dd>loads the modules that are part of package_contents. package_name is a string and package_contents is a list of string tuples (file_name, module_code)</dd></dl>

</div>
<div class="section" id="module-runtime.rt">
<h2>The <tt class="xref docutils literal"><span class="pre">rt</span></tt> Module</h2>
<p>Created on 10/08/2009</p>
<p>&#64;author: eh01</p>
<dl class="class">
<dt id="runtime.rt.Runtime">
<em class="property">class </em><tt class="descclassname">runtime.rt.</tt><tt class="descname">Runtime</tt></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<dl class="method">
<dt id="runtime.rt.Runtime.cb_node_shutdown">
<tt class="descname">cb_node_shutdown</tt><big>(</big><em>spaces_context</em>, <em>uri</em><big>)</big></dt>
<dd><p>Shutdown the node.</p>
<p>Shutdowns the node currently by stopping all the tasks. Returns the exit code to specify a shutdown or a restart.</p>
<p>Returns: int.</p>
<p>Parameters:
spaces_context &#8211; runtime.spaces.SpacesContext: Context of the runtime.
uri &#8211; datastore.uri.Uri: uri called to shutdown</p>
</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.create_task">
<tt class="descname">create_task</tt><big>(</big><em>task_fully_qualified_path</em>, <em>spaces</em>, <em>task_uri</em>, <em>task_def_rs</em><big>)</big></dt>
<dd>return a instance of the task specified by the qualified path and task definition</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.create_tasks_from_configuration">
<tt class="descname">create_tasks_from_configuration</tt><big>(</big><em>configuration</em>, <em>spaces_context</em><big>)</big></dt>
<dd>return a list of created tasks defined in the manifest</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.first_time">
<tt class="descname">first_time</tt><big>(</big><em>file_repository_location</em>, <em>distribution_name</em><big>)</big></dt>
<dd>code to run the first time the application is started up</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.get_class_type">
<tt class="descname">get_class_type</tt><big>(</big><em>module_path</em>, <em>class_name</em><big>)</big></dt>
<dd>return type of the class</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.get_configuration_files">
<tt class="descname">get_configuration_files</tt><big>(</big><em>ds</em><big>)</big></dt>
<dd><p>Return configuration files as resources</p>
<p>The method is passed a instance of datastore where it retrieves all
the configuration files.</p>
<p>Return: List</p>
<p>Keyword arguments:
ds &#8211; datastore.database.Datastore: datastore to be queried.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.initialise_spaces">
<tt class="descname">initialise_spaces</tt><big>(</big><em>spaces_context</em>, <em>ds=None</em>, <em>config_files=None</em><big>)</big></dt>
<dd><p>Initalise spaces from configuration.</p>
<p>The method is passed a instance of SpacesContext which it uses to initialises spaces with:
- all the uri namespaces bindings in either the configuration files found on the
datastore, or the configuration files passed into the method.
- the configuration files.</p>
<p>Return: runtime.spaces.SpacesContext</p>
<p>Keyword arguments:
spaces_context &#8211; runtime.spaces.SpacesContext: SpacesContext used to initialise spaces.
ds &#8211; datastore.database.DataStore: Datastore to retrieve config files from.
config_files &#8211; List: list of resource config files.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.initialise_spaces_with_local_config_files">
<tt class="descname">initialise_spaces_with_local_config_files</tt><big>(</big><em>spaces_context</em><big>)</big></dt>
<dd><p>Initalise spaces from configuration.</p>
<p>The method is passed a instance of SpacesContext which it uses to initialises spaces with:
- all the uri namespaces bindings in either the configuration files found on the
local file system.
- the configuration files. 
NOTE: This is solely used for writing tests at the moment.</p>
<p>Return: runtime.spaces.SpacesContext</p>
<p>Keyword arguments:
spaces_context &#8211; runtime.spaces.SpacesContext: SpacesContext used to initialise spaces.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.post_start">
<tt class="descname">post_start</tt><big>(</big><em>spaces_context</em><big>)</big></dt>
<dd><p>Handle post start events.</p>
<p>Handles events after the node has successfully started. This includes shutting down of the node.</p>
<p>Returns: None</p>
<p>Parameters:
spaces_context &#8211; runtime.spaces.SpacesContext: Context of the runtime.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.start">
<tt class="descname">start</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.stop_tasks">
<tt class="descname">stop_tasks</tt><big>(</big><em>spaces_context</em>, <em>uri</em><big>)</big></dt>
<dd><p>Stop tasks.</p>
<p>Stops the tasks registered under the uri. It does this by checking if the resource at that uri is a 
task definition resource. If it is, then it will attempt to stop the task by deleting the resource at the
uri.</p>
<p>Returns: None.</p>
<p>Parameters:
spaces_context &#8211; runtime.spaces.SpacesContext: Context of the runtime.
uri &#8211; datastore.uri.Uri: uri of where all the tasks are located</p>
</dd></dl>

<dl class="method">
<dt id="runtime.rt.Runtime.update_packages">
<tt class="descname">update_packages</tt><big>(</big><em>ds</em>, <em>spaces_context</em><big>)</big></dt>
<dd></dd></dl>

</dd></dl>

<dl class="exception">
<dt id="runtime.rt.StartupException">
<em class="property">exception </em><tt class="descclassname">runtime.rt.</tt><tt class="descname">StartupException</tt></dt>
<dd>Bases: <tt class="xref docutils literal"><span class="pre">exceptions.Exception</span></tt></dd></dl>

</div>
<div class="section" id="module-runtime.spaces">
<h2>The <tt class="xref docutils literal"><span class="pre">spaces</span></tt> Module</h2>
<p>Created on 17/09/2009</p>
<p>&#64;author: Tony Allan, Edward Huynh</p>
<dl class="class">
<dt id="runtime.spaces.Node">
<em class="property">class </em><tt class="descclassname">runtime.spaces.</tt><tt class="descname">Node</tt><big>(</big><em>part=None</em><big>)</big></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<p>Node in a network of nodes.</p>
<p>A network of nodes make up a tree. Each node has a reference to its parent 
and its children. It also stores a resource associated with the node, in 
addition to the task that have processes and watches against it.</p>
<dl class="method">
<dt id="runtime.spaces.Node.add_child_node">
<tt class="descname">add_child_node</tt><big>(</big><em>node</em><big>)</big></dt>
<dd><p>Return child node that was added.</p>
<p>Adds the node as a child to the current node</p>
<p>Return: runtime.spaces.Node</p>
<p>Keyword arguments:
node &#8211; runtime.spaces.Node: node to be added</p>
</dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.children">
<tt class="descname">children</tt></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.delete_node">
<tt class="descname">delete_node</tt><big>(</big><em>node</em><big>)</big></dt>
<dd><p>Return child node that was deleted.</p>
<p>Removes the node from its parent node.</p>
<p>Return: runtime.spaces.Node</p>
<p>Keyword arguments:
node &#8211; runtime.spaces.Node: node to be deleted</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.find_node">
<tt class="descname">find_node</tt><big>(</big><em>part</em><big>)</big></dt>
<dd><p>Return child node that matches part.</p>
<p>Finds a node that is a direct child of this node that has part that 
matches the part argument.</p>
<p>Return: runtime.spaces.Node</p>
<p>Keyword arguments:
part &#8211; String: part that makes up the path of the uri</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_children">
<tt class="descname">get_children</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_parent">
<tt class="descname">get_parent</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_part">
<tt class="descname">get_part</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_process">
<tt class="descname">get_process</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_process_all">
<tt class="descname">get_process_all</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_resource">
<tt class="descname">get_resource</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_resource_wait">
<tt class="descname">get_resource_wait</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_watch">
<tt class="descname">get_watch</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.get_watch_all">
<tt class="descname">get_watch_all</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.parent">
<tt class="descname">parent</tt></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.part">
<tt class="descname">part</tt></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.process">
<tt class="descname">process</tt></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.process_all">
<tt class="descname">process_all</tt></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.resource">
<tt class="descname">resource</tt></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.set_parent">
<tt class="descname">set_parent</tt><big>(</big><em>parent_node</em><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.set_resource">
<tt class="descname">set_resource</tt><big>(</big><em>resource</em><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Node.uri">
<tt class="descname">uri</tt><big>(</big><big>)</big></dt>
<dd><p>Return uri of node.</p>
<p>Returns a URI object representing the uri associated with the node</p>
<p>Return: datastore.uri.Uri</p>
</dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.watch">
<tt class="descname">watch</tt></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.Node.watch_all">
<tt class="descname">watch_all</tt></dt>
<dd></dd></dl>

</dd></dl>

<dl class="class">
<dt id="runtime.spaces.Spaces">
<em class="property">class </em><tt class="descclassname">runtime.spaces.</tt><tt class="descname">Spaces</tt><big>(</big><em>logger=None</em><big>)</big></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<p>This class defines the API used between components of Yarra.
It uses a data paradigm loosely modelled after REST, JavaSpaces and Linda.</p>
<p>The Spaces class manages all data. SpacesContext delegates its methods to
Spaces. SpacesContext adds a context (self) when it invokes Spaces methods that 
require a queue for a callback. When a callback needs to be invoked, its 
reference and parameters (callback_func, method, uri, res and result) are 
placed on the SpacesContext that specified the callback. This means that a 
callback will always be executed in the same thread that defined it.</p>
<p>To the user of Spaces, all data appears to be stored within Spaces.
process() and process_all, allow dynamic resources to be fetched, created
or deleted.</p>
<p>While common usage is to work with Resources as the value for each URI key, 
any object may be passed.</p>
<p>If the last character of a URI is a slash, assume that it refers to a collection.
A collection is the same as a Web index and it will generally be possible to 
navigate from the root to any URI.</p>
<dl class="docutils">
<dt>The collection uri without the trailing slash refers to the collection object.</dt>
<dd><a class="reference external" href="http:/aaa/a.b.c/">http:/aaa/a.b.c/</a> is a collection.
<a class="reference external" href="http:/aaa/a.b.c">http:/aaa/a.b.c</a> is the collection index.</dd>
</dl>
<p>If a callback is specified for get, put or delete, the method will return
immediately. The callback will be invoked when a result is available.
SpacesContext</p>
<dl class="method">
<dt id="runtime.spaces.Spaces.call_all_watches">
<tt class="descname">call_all_watches</tt><big>(</big><em>node</em>, <em>method</em>, <em>uri</em>, <em>return_value</em>, <em>exception</em><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.delete">
<tt class="descname">delete</tt><big>(</big><em>uri</em>, <em>spaces_context</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Deletes the resource associated with this URI in spaces.</p>
<p>If callback is None, return the Resource that is to be deleted, otherwise 
return None and pass the Resource to callback via the spaces_context. If 
the Resource was not found or deleted, return None.</p>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd>method - always &#8216;delete&#8217;
uri - the uri passed to delete
return_value - will be None for this case.
result - None or an exception class.
spaces_context - Context which the &#8216;method&#8217; was called from.
<a href="#id1"><span class="problematic" id="id2">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</dd>
</dl>
<p>Return: None</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.   
<a href="#id3"><span class="problematic" id="id4">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.delete_process">
<tt class="descname">delete_process</tt><big>(</big><em>process_ref</em><big>)</big></dt>
<dd><p>Delete the specified process or process_all callback.</p>
<p>The delete is based on the process_ref passed in as a parameter</p>
<p>Return: None</p>
<p>Keyword arguments:
process_ref &#8211; UUID: reference to process when saved.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.delete_watch">
<tt class="descname">delete_watch</tt><big>(</big><em>watch_ref</em><big>)</big></dt>
<dd><p>Delete the specified watch or watch_all callback.</p>
<p>The delete is based on the watch_ref passed in as a parameter</p>
<p>Return: None</p>
<p>Keyword arguments:
watch_ref &#8211; UUID: reference to watch when saved.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.dump">
<tt class="descname">dump</tt><big>(</big><em>spaces_context</em>, <em>start_uri=''</em><big>)</big></dt>
<dd>List all URI&#8217;s in spaces, optionally starting at a particular level
Mostly to assist in development.</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.find">
<tt class="descname">find</tt><big>(</big><em>spaces_context</em>, <em>uri=None</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Return a list of Uri objects that match the uri prefix.</p>
<p>Scope is limited to the next level in the uri path
If uri is None then a list of the top level uri&#8217;s is returned.</p>
<blockquote>
<a class="reference external" href="http://aaa/">http://aaa/</a>
<a class="reference external" href="http://bbb/">http://bbb/</a></blockquote>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd>method - always &#8216;find&#8217;
uri - the uri passed to find
return_value - will be a list of URI&#8217;s.
result - None or an exception class.
spaces_context - Context which the &#8216;method&#8217; was called from.
<a href="#id5"><span class="problematic" id="id6">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</dd>
</dl>
<p>Return: List</p>
<p>Keyword arguments:
uri &#8211; URI: uri   
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.
<a href="#id7"><span class="problematic" id="id8">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.find_process_all_callback">
<tt class="descname">find_process_all_callback</tt><big>(</big><em>curr_node</em>, <em>method</em><big>)</big></dt>
<dd><p>Return most relevant process_all callback for current node.</p>
<p>The first process_all callback associated with the uri will be returned. 
First check the &#8216;process_all&#8217; callback for the current node. If there is 
not a process associated with the current node, then look for the first 
&#8216;process_all&#8217; callback associated with the parent nodes.</p>
<p>Return: Tuple</p>
<p>Keyword arguments:
curr_node &#8211; runtime.spaces.Node: The node to find the callback for.
method &#8211; String: the method to find the watch for</p>
<blockquote>
(i.e. &#8216;get&#8217;, &#8216;find&#8217;, &#8216;delete&#8217;, &#8216;put&#8217;).</blockquote>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.find_process_callback">
<tt class="descname">find_process_callback</tt><big>(</big><em>curr_node</em>, <em>method</em><big>)</big></dt>
<dd><p>Return most relevant process or process_all callback for current node.</p>
<p>The first process callback associated with the uri will be returned. First 
check the &#8216;process&#8217; callback for the current node. If there is not a process 
associated with the current node, then look for the first &#8216;process_all&#8217;  
callback associated with the parent nodes.</p>
<p>Return: Tuple</p>
<p>Keyword arguments:
curr_node &#8211; runtime.spaces.Node: The node to find the callback for.
method &#8211; String: the method to find the watch for</p>
<blockquote>
(i.e. &#8216;get&#8217;, &#8216;find&#8217;, &#8216;delete&#8217;, &#8216;put&#8217;).</blockquote>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.get">
<tt class="descname">get</tt><big>(</big><em>uri</em>, <em>spaces_context</em>, <em>callback=None</em>, <em>wait=False</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Fetch the Resource associated with this URI.</p>
<p>If callback is None, return the Resource, otherwise return None and pass 
resource to callback via the spaces_context. If the resource is not found, 
return none. If wait is true, the method will block until the resource is added to the uri,
or issue a callback when the resource is added.</p>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd>method - always &#8216;get&#8217;
uri - the uri passed to get
return_value - will be the requested Resource.
result - None or an exception class.
spaces_context - Context which the &#8216;method&#8217; was called from.
<a href="#id9"><span class="problematic" id="id10">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</dd>
</dl>
<p>Return: datastore.resource.Resource</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.
<a href="#id11"><span class="problematic" id="id12">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.handle_return">
<tt class="descname">handle_return</tt><big>(</big><em>callback</em>, <em>method</em>, <em>return_data</em>, <em>uri</em>, <em>node</em>, <em>exception</em>, <em>spaces_context</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Handle return data</p>
<p>Handles the return value by callback or synchronise return.</p>
<p>Return: Anything</p>
<p>Keyword arguments:
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<dl class="docutils">
<dt>method &#8211; string: the method name that was called. </dt>
<dd>(i.e. &#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;)</dd>
</dl>
<p>return_data datastore.resource.Resource: the data to return to caller.
uri &#8211; URI: uri that was called.
node &#8211; runtime.spaces.Node: Node that is associated with the URI.
exception &#8211; Exception: Any exception to pass back to the caller.
spaces_context &#8211; runtime.spaces.SpacesContext: SpacesContext of the caller.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.issue_process_callback">
<tt class="descname">issue_process_callback</tt><big>(</big><em>process_callback_info</em>, <em>caller_callback</em>, <em>caller_spaces_context</em>, <em>method</em>, <em>uri</em>, <em>node</em>, <em>res</em>, <em>**caller_kwargs</em><big>)</big></dt>
<dd><p>Issues the process callback provided by process_callback_info</p>
<p>Issues the process callback and setups the return mechanism to allow the 
callback to return the data.</p>
<p>Return: Anything</p>
<p>Keyword arguments:
process_callback_info &#8211; Tuple: contains the process_callback, process_spaces_context and the kwargs.</p>
<blockquote>
The process_callback the method name (String) or a references 
to the method to be called back on a Process Task.
The process_spaces_context is the context that was used to register the process.
The kwargs is the keyword arguements passed to &#8216;process&#8217; when the process was registered</blockquote>
<dl class="docutils">
<dt>caller_callback &#8211; String/Method: the method name (String) or a references </dt>
<dd>to the method to be called back on a Caller Task.</dd>
<dt>caller_spaces_context &#8211; SpacesContext: Provides context to the callback </dt>
<dd>of the Caller Task.</dd>
<dt>method &#8211; string: the method name that was called. </dt>
<dd>(i.e. &#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;)</dd>
</dl>
<p>uri &#8211; Uri: the uri from the caller request
node &#8211; Node: the node associated with the uri
res &#8211; datastore.resource.Resource: Resource that was passed to spaces. NOTE: this is only populated when &#8216;put&#8217; is called.
caller_kwargs &#8211; Dictionary: The kwargs supplied when the caller called a method on spaces.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.load_bindings">
<tt class="descname">load_bindings</tt><big>(</big><em>ns</em><big>)</big></dt>
<dd>load bindings to spaces</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.log">
<tt class="descname">log</tt><big>(</big><em>text=None</em>, <em>level=20</em><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.process">
<tt class="descname">process</tt><big>(</big><em>uri</em>, <em>callback_dict</em>, <em>spaces_context</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Registers callbacks against a uri to process all method 
(i.e. &#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217; and &#8216;find&#8217;) on the uri</p>
<p>The callback is called to process the specified methods called on the uri. 
The task that initiated the request will not get a result until this method 
has returned. Returns a process_ref that is required to delete the process 
callback. An exception is raised if this particular uri already has a 
process callback with the same method and uri. There should be a single 
&#8216;owner&#8217; of this part of API. If more than one process or process_all 
applies to this uri, then only the most specific is applied.</p>
<p>Valid values for method are: &#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;, &#8216;remove&#8217;</p>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd><p class="first">method - &#8216;get&#8217;, &#8216;put&#8217;, &#8216;find&#8217;, &#8216;delete&#8217; or &#8216;remove&#8217;
uri - the uri that is being processed
return_value - any value passed on by spaces. Usually this will be</p>
<blockquote>
None, except for the case where the</blockquote>
<dl class="docutils">
<dt>method is &#8216;put&#8217;, in which the resource being put is passed in through </dt>
<dd>this parameter.</dd>
</dl>
<p class="last">result - None or an exception class.
spaces_context - New context for each cb invoked.
<a href="#id13"><span class="problematic" id="id14">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</p>
</dd>
<dt>The callback must return:</dt>
<dd>A Resource or None for a get.
A Uri or None for a put.
The resource being deleted or None for a delete.
A list of Uri or None for a find</dd>
</dl>
<p>Return: UUID</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback_dict &#8211; Dict: key is the method (e.g &#8216;get&#8217;). value is either the</p>
<blockquote>
method name (String) or a references to the method to be called back 
on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.   
<a href="#id15"><span class="problematic" id="id16">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback methods.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.process_all">
<tt class="descname">process_all</tt><big>(</big><em>uri</em>, <em>callback_dict</em>, <em>spaces_context</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Registers callbacks against a uri prefix to process all method 
(i.e. &#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217; and &#8216;find&#8217;) on the uri</p>
<p>The callback is called to process the specified methods called that 
match this uri prefix. The task that initiated the request will not 
get a result until this method has returned.
See process() for additional information.
uri is the uri prefix to process. If it is None, all uri changes are processed.
An exception is raised if this particular uri prefix already has a process 
callback with the same method and uri prefix.</p>
<p>Return: UUID</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback_dict &#8211; Dict: key is the method (e.g &#8216;get&#8217;). value is either the</p>
<blockquote>
method name (String) or a references to the method to be called back 
on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.   
<a href="#id17"><span class="problematic" id="id18">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback methods.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.put">
<tt class="descname">put</tt><big>(</big><em>uri</em>, <em>res</em>, <em>spaces_context</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Save the specified Resource using this URI as its key.</p>
<p>If the last character of the URI is a slash, generate a UUID and append 
it to the URI. If a process is defined for this particular uri, then don&#8217;t 
perform this default action.</p>
<p>If callback is None, return the saved URI, otherwise return None and pass 
the saved URI to callback via the spaces_context.</p>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd><p class="first">method - always &#8216;put&#8217;
uri - the new uri (which will be the one passed unless this is an</p>
<blockquote>
addition to a collection)</blockquote>
<p>return_value - will be the Uri of where the resource lives.
result - None or an exception class.
spaces_context - Context which the &#8216;method&#8217; was called from.
<a href="#id19"><span class="problematic" id="id20">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</p>
<p class="last">If there was a non-fatal fault but a URI was returned, then any retry
should use the returned uri to prevent duplicate resource creation.</p>
</dd>
</dl>
<p>Return: datastore.uri.Uri</p>
<p>Keyword arguments:
uri &#8211; URI: uri
res &#8211; Resource: resource to put in the spaces
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.  
<a href="#id21"><span class="problematic" id="id22">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.remove">
<tt class="descname">remove</tt><big>(</big><em>uri</em>, <em>spaces_context</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Returns and deletes the resource associated with this URI in spaces.</p>
<p>If callback is None, return the Resource that is to be deleted, otherwise 
return None and pass the Resource to callback via the spaces_context. If 
the Resource was not found or deleted, return None.</p>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd>method - always &#8216;delete&#8217;
uri - the uri passed to delete
return_value - will be the Resource removed from the uri.
result - None or an exception class.
spaces_context - Context which the &#8216;method&#8217; was called from.
<a href="#id23"><span class="problematic" id="id24">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</dd>
</dl>
<p>Return: datastore.resource.Resource</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.  
<a href="#id25"><span class="problematic" id="id26">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.return_from_callback">
<tt class="descname">return_from_callback</tt><big>(</big><em>spaces_context</em>, <em>return_value=None</em>, <em>exception=None</em><big>)</big></dt>
<dd><p>Return result from callback to the caller</p>
<p>When task callback methods need to return data to spaces as a result of it 
being invoked, the callback method should call this method and supply the 
spaces_context and the return value. This spaces_context is used to retrieve 
information about the caller whose actions resulted in the callback being 
called. The return data is then passed back to the caller (either through 
a return or another callback).</p>
<p>Return: None</p>
<p>Keyword arguments:
spaces_context &#8211; SpacesContext: identifier for dict to retrieve callback</p>
<blockquote>
return information.</blockquote>
<p>return_value &#8211; ?: Any data that is to be returned to the caller.
exception &#8211; Exception: Any Exception that needs to be returned to caller</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.set_log">
<tt class="descname">set_log</tt><big>(</big><em>logger='yarra.runtime.spaces.Spaces'</em>, <em>level=None</em><big>)</big></dt>
<dd><dl class="docutils">
<dt>Levels: logging.DEBUG, logging.INFO, logging.WARNING, </dt>
<dd>logging.ERROR, logging.CRITICAL</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.uri">
<tt class="descname">uri</tt><big>(</big><em>uri_prefix=None</em><big>)</big></dt>
<dd>return uri object with uri_prefix</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.uuid">
<tt class="descname">uuid</tt><big>(</big><big>)</big></dt>
<dd>generate a random uuid.</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.watch">
<tt class="descname">watch</tt><big>(</big><em>methods</em>, <em>uri</em>, <em>spaces_context</em>, <em>callback</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Registers a watch against the uri.</p>
<p>The callback is called whenever the specified methods are called on the 
uri. This method does not delay the action it is watching.</p>
<p>A typical use of watch is to update a collection index, when a member of
the collection is changed.</p>
<p>There can be multiple watch and watch_all specified. Each one that matches
the method(s) and uri will be called.</p>
<p>Valid values for method are: &#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;, &#8216;remove&#8217;</p>
<dl class="docutils">
<dt>Callback will be called with the following arguments:</dt>
<dd><p class="first">method - &#8216;get&#8217;, &#8216;put&#8217;, &#8216;find&#8217;, &#8216;delete&#8217; or &#8216;remove&#8217;
uri - the uri that is being processed
return_value - any value returned by spaces.
result - None or an exception class.
spaces_context - New context for each cb invoked.
<a href="#id27"><span class="problematic" id="id28">**</span></a>kwargs - Additional Keyword arguments passed in from the parameters of this method.</p>
<p class="last">No return data is expected from the callback.</p>
</dd>
</dl>
<p>Return: UUID</p>
<p>Keyword arguments:
methods &#8211; List: List contain one or more of the following:</p>
<blockquote>
&#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;</blockquote>
<p>uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.      
<a href="#id29"><span class="problematic" id="id30">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.Spaces.watch_all">
<tt class="descname">watch_all</tt><big>(</big><em>methods</em>, <em>uri</em>, <em>spaces_context</em>, <em>callback</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Registers a watch_all against the uri.</p>
<p>The callback is called whenever the specified methods are called that
match this uri prefix. This method does not delay the action it is watching.</p>
<p>See watch() for additional information.</p>
<p>uri is the uri prefix to watch. If it is None, all uri changes are detected.</p>
<p>The callback uri is the actual uri that changed rather than the prefix 
that was passed to watch().</p>
<p>Return: UUID</p>
<p>Keyword arguments:
methods &#8211; List: List contain one or more of the following:</p>
<blockquote>
&#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;</blockquote>
<p>uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p>spaces_context &#8211; SpacesContext: Provides context to the Caller&#8217;s callback.   
<a href="#id31"><span class="problematic" id="id32">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="runtime.spaces.SpacesContext">
<em class="property">class </em><tt class="descclassname">runtime.spaces.</tt><tt class="descname">SpacesContext</tt><big>(</big><em>spaces</em>, <em>queue</em><big>)</big></dt>
<dd><p>SpacesContext provides context for calls to Spaces.</p>
<p>Tasks uses SpacesContext to make calls to Spaces. SpacesContext delegates 
calls to Spaces. It also provides access to a queue where callbacks are queued 
by Spaces to be processed by the task</p>
<dl class="method">
<dt id="runtime.spaces.SpacesContext.delete">
<tt class="descname">delete</tt><big>(</big><em>uri</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.delete. See Spaces.delete for more detailed description.</p>
<p>Return: None</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p><a href="#id33"><span class="problematic" id="id34">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.delete_process">
<tt class="descname">delete_process</tt><big>(</big><em>process_ref</em><big>)</big></dt>
<dd><p>Delegates to Spaces.delete_process. See Spaces.delete_process for more 
detailed description.</p>
<p>Return: None</p>
<p>Keyword arguments:
process_ref &#8211; a reference returned when the process or process_all was</p>
<blockquote>
created.</blockquote>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.delete_watch">
<tt class="descname">delete_watch</tt><big>(</big><em>watch_ref</em><big>)</big></dt>
<dd><p>Delegates to Spaces.delete_watch. See Spaces.delete_watch for more detailed 
description.</p>
<p>Return: None</p>
<p>Keyword arguments:
watch_ref &#8211; a reference returned when the watch or watch_all was created.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.dump">
<tt class="descname">dump</tt><big>(</big><em>start_uri=''</em><big>)</big></dt>
<dd>List all URI&#8217;s in spaces, optionally starting at a particular level
Mostly to assist in development.</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.find">
<tt class="descname">find</tt><big>(</big><em>uri=None</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.find. See Spaces.find for more detailed description.</p>
<p>Return: List</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references 
<a href="#id35"><span class="problematic" id="id36">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.get">
<tt class="descname">get</tt><big>(</big><em>uri</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.get. See Spaces.get for more detailed description.</p>
<p>Return: datastore.resource.Resource</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p><a href="#id37"><span class="problematic" id="id38">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.get_queue">
<tt class="descname">get_queue</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.get_spaces">
<tt class="descname">get_spaces</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.get_wait">
<tt class="descname">get_wait</tt><big>(</big><em>uri</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.get. See Spaces.get for more detailed description.</p>
<p>Return: datastore.resource.Resource</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p><a href="#id39"><span class="problematic" id="id40">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.load_bindings">
<tt class="descname">load_bindings</tt><big>(</big><em>ns</em><big>)</big></dt>
<dd>load bindings to spaces</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.process">
<tt class="descname">process</tt><big>(</big><em>uri</em>, <em>get=None</em>, <em>find=None</em>, <em>put=None</em>, <em>delete=None</em>, <em>remove=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.process. See Spaces.process for more detailed description.</p>
<p>Return: UUID. A process reference - needed for a subsequent delete_process().</p>
<p>Keyword arguments:
uri &#8211; URI: uri
get, find, put, delete, and remove are either the method name (String)</p>
<blockquote>
or a reference to the method to be called back on a Task.</blockquote>
<dl class="docutils">
<dt>spaces_queue &#8211; Queue: Queue to place the callback arguments on for the </dt>
<dd>Task&#8217;s callback method.</dd>
</dl>
<p><a href="#id41"><span class="problematic" id="id42">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback methods.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.process_all">
<tt class="descname">process_all</tt><big>(</big><em>uri</em>, <em>get=None</em>, <em>find=None</em>, <em>put=None</em>, <em>delete=None</em>, <em>remove=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.process_all. See Spaces.process_all for more detailed 
description.</p>
<p>Return: UUID. A process reference - needed for a subsequent delete_process().</p>
<p>Keyword arguments:
uri &#8211; URI: uri
get, find, put, delete, and remove are either the method name (String)</p>
<blockquote>
or a reference to the method to be called back on a Task.</blockquote>
<dl class="docutils">
<dt>spaces_queue &#8211; Queue: Queue to place the callback arguments on for the </dt>
<dd>Task&#8217;s callback method.</dd>
</dl>
<p><a href="#id43"><span class="problematic" id="id44">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback methods.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.put">
<tt class="descname">put</tt><big>(</big><em>uri</em>, <em>res</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.put. See Spaces.put for more detailed description.</p>
<p>Return: datastore.uri.Uri</p>
<p>Keyword arguments:
uri &#8211; URI: uri
res &#8211; Resource: resource to put in the spaces
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p><a href="#id45"><span class="problematic" id="id46">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.SpacesContext.queue">
<tt class="descname">queue</tt></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.remove">
<tt class="descname">remove</tt><big>(</big><em>uri</em>, <em>callback=None</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.remove. See Spaces.delete for more detailed description.</p>
<p>Return: datastore.resource.Resource</p>
<p>Keyword arguments:
uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<p><a href="#id47"><span class="problematic" id="id48">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method if specified. Otherwise it is ignored.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.return_from_callback">
<tt class="descname">return_from_callback</tt><big>(</big><em>callback_return_id</em>, <em>return_value=None</em>, <em>exception=None</em><big>)</big></dt>
<dd><p>Delegates to Spaces.return_from_callback. See Spaces.return_from_callback 
for more detailed description.</p>
<p>Return: None</p>
<p>Keyword arguments:
callback_return_id &#8211; UUID: identifier for dict to retrieve callback</p>
<blockquote>
return information.</blockquote>
<p>return_value &#8211; ?: Any data that is to be returned to the caller.</p>
</dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.SpacesContext.spaces">
<tt class="descname">spaces</tt></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.uri">
<tt class="descname">uri</tt><big>(</big><em>uri_prefix=None</em><big>)</big></dt>
<dd>return uri object with uri_prefix</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.uuid">
<tt class="descname">uuid</tt><big>(</big><big>)</big></dt>
<dd>Delegates to Spaces.uuid. See Spaces.uuid for more detailed description.</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.watch">
<tt class="descname">watch</tt><big>(</big><em>methods</em>, <em>uri</em>, <em>callback</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.watch. See Spaces.watch for more detailed description.</p>
<p>Return: UUID. A watch reference - needed for a subsequent delete_watch().</p>
<p>Keyword arguments:</p>
<dl class="docutils">
<dt>methods &#8211; List: List contain one or more of the following: </dt>
<dd>&#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;</dd>
</dl>
<p>uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<dl class="docutils">
<dt>spaces_queue &#8211; Queue: Queue to place the callback arguments on for the </dt>
<dd>Task&#8217;s callback method.</dd>
</dl>
<p><a href="#id49"><span class="problematic" id="id50">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.SpacesContext.watch_all">
<tt class="descname">watch_all</tt><big>(</big><em>methods</em>, <em>uri</em>, <em>callback</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Delegates to Spaces.watch_all. See Spaces.watch_all for more detailed 
description.</p>
<p>Return: UUID. A watch reference - needed for a subsequent delete_watch().</p>
<p>Keyword arguments:
methods &#8211; List: List contain one or more of the following:</p>
<blockquote>
&#8216;get&#8217;, &#8216;put&#8217;, &#8216;delete&#8217;, &#8216;find&#8217;</blockquote>
<p>uri &#8211; URI: uri
callback &#8211; String/Method: Either the method name (String) or a references</p>
<blockquote>
to the method to be called back on a Task.</blockquote>
<dl class="docutils">
<dt>spaces_queue &#8211; Queue: Queue to place the callback arguments on for the </dt>
<dd>Task&#8217;s callback method.</dd>
</dl>
<p><a href="#id51"><span class="problematic" id="id52">**</span></a>kwargs &#8211; Dictionary: Additional keyword arguments to pass to the callback method.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="runtime.spaces.UriTree">
<em class="property">class </em><tt class="descclassname">runtime.spaces.</tt><tt class="descname">UriTree</tt></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<p>Tree consisting of a network of nodes.</p>
<p>The Tree class allows us to create a tree and find, add and delete nodes from 
it. Each node in the tree represents a part of a uri. The path from a node to 
its root node represents a uri. Each Node contains the watches, processes and 
resource associated with a uri.</p>
<p>NOTE: Always use the UriTree API to add, find and delete nodes in the tree. 
The API that UriTree offers to manipulate the tree is thread-safe and we can 
not guarantee thread safety if users try to update the tree or a node through  
the Node API.</p>
<dl class="method">
<dt id="runtime.spaces.UriTree.add_node">
<tt class="descname">add_node</tt><big>(</big><em>node</em>, <em>uri</em><big>)</big></dt>
<dd><p>Return node that was added.</p>
<p>Adds the node to the tree</p>
<p>Return: runtime.spaces.Node</p>
<p>Keyword arguments:
node &#8211; runtime.spaces.Node: node to be added</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.UriTree.delete_node">
<tt class="descname">delete_node</tt><big>(</big><em>uri</em><big>)</big></dt>
<dd><p>Return node that was deleted.</p>
<p>Removes the node from the tree and any of its children.</p>
<p>Return: runtime.spaces.Node</p>
<p>Keyword arguments:
node &#8211; runtime.spaces.Node: node to be deleted</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.UriTree.find_node">
<tt class="descname">find_node</tt><big>(</big><em>uri</em><big>)</big></dt>
<dd><p>Return child node that matches the uri.</p>
<p>Finds a node in the tree that matches the uri.</p>
<p>Return: runtime.spaces.Node</p>
<p>Keyword arguments:
uri &#8211; Uri: uri of child to find</p>
</dd></dl>

<dl class="method">
<dt id="runtime.spaces.UriTree.find_non_blank_parent_node">
<tt class="descname">find_non_blank_parent_node</tt><big>(</big><em>node</em><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.spaces.UriTree.get_root_node">
<tt class="descname">get_root_node</tt><big>(</big><big>)</big></dt>
<dd></dd></dl>

<dl class="attribute">
<dt id="runtime.spaces.UriTree.root_node">
<tt class="descname">root_node</tt></dt>
<dd></dd></dl>

</dd></dl>

</div>
<div class="section" id="module-runtime.task">
<h2>The <tt class="xref docutils literal"><span class="pre">task</span></tt> Module</h2>
<p>Created on 20/08/2009</p>
<p>&#64;author: Edward Huynh, Tony Allan</p>
<dl class="exception">
<dt id="runtime.task.NonTaskException">
<em class="property">exception </em><tt class="descclassname">runtime.task.</tt><tt class="descname">NonTaskException</tt></dt>
<dd>Bases: <tt class="xref docutils literal"><span class="pre">exceptions.Exception</span></tt></dd></dl>

<dl class="class">
<dt id="runtime.task.Task">
<em class="property">class </em><tt class="descclassname">runtime.task.</tt><tt class="descname">Task</tt><big>(</big><em>spaces</em>, <em>task_uri</em>, <em>task_def_rs</em>, <em>logger='yarra.runtime.task'</em><big>)</big></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">threading.Thread</span></tt></p>
<p>Each task is a thread with its own SpacesContext. Each sub-class
of task defines a set of callback methods that watch or process on specific methods 
(i.e. &#8216;get&#8217;, &#8216;find&#8217;, &#8216;delete&#8217;, &#8216;put&#8217;) called on a particular URIs in Spaces.
A Task callback method has a defined signature which consists of the following
parameters:</p>
<blockquote>
method - the method invoked on the uri (i.e. &#8216;get&#8217;, &#8216;find&#8217;, &#8216;delete&#8217;, &#8216;put&#8217;) 
uri - the uri invoked on Spaces
return_value - the value returned by Spaces. This can be a datastore.resource.Resource or datastore.uri.Uri
result - None or an exception class.</blockquote>
<dl class="method">
<dt id="runtime.task.Task.cb_start">
<tt class="descname">cb_start</tt><big>(</big><em>method</em>, <em>uri</em>, <em>new_uri</em>, <em>result</em>, <em>context</em>, <em>**kwargs</em><big>)</big></dt>
<dd>Default implementation of the start method.
The first callback invoked for the task.
Normally overridden.</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.cb_stop">
<tt class="descname">cb_stop</tt><big>(</big><em>method</em>, <em>uri</em>, <em>deleted_res</em>, <em>result</em>, <em>context</em>, <em>**kwargs</em><big>)</big></dt>
<dd><p>Default implementation of the stop method.
The last callback invoked for this task after stop_task() is called.
Overridden if cleanup needed.</p>
<p>Note: clean-up cannot access any spaces function that returns a value 
or otherwise access the queue because the callback loop has already 
terminated.</p>
</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.cb_stop_test">
<tt class="descname">cb_stop_test</tt><big>(</big><em>method</em>, <em>uri</em>, <em>res</em>, <em>result</em>, <em>context</em>, <em>**kwargs</em><big>)</big></dt>
<dd>testing only.</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.cb_update">
<tt class="descname">cb_update</tt><big>(</big><em>method</em>, <em>uri</em>, <em>new_uri</em>, <em>result</em>, <em>context</em>, <em>**kwargs</em><big>)</big></dt>
<dd>Default implementation of the update method.
Called whenever the task resource is updated by a put.
Overridden if external updates are expected.</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.log">
<tt class="descname">log</tt><big>(</big><em>text=None</em>, <em>level=20</em>, <em>**kwargs</em><big>)</big></dt>
<dd></dd></dl>

<dl class="method">
<dt id="runtime.task.Task.log_level">
<tt class="descname">log_level</tt><big>(</big><em>level</em><big>)</big></dt>
<dd>Levels: logging.TRACE, logging.DEBUG, logging.DEVEL, logging.INFO, 
logging.WARNING, logging.ERROR, logging.CRITICAL</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.run">
<tt class="descname">run</tt><big>(</big><big>)</big></dt>
<dd>Loop, processing callback&#8217;s until stopped.</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.task_start">
<tt class="descname">task_start</tt><big>(</big><big>)</big></dt>
<dd>Testing support - Start the thread and wait until the start message is processed.</dd></dl>

<dl class="method">
<dt id="runtime.task.Task.task_stop">
<tt class="descname">task_stop</tt><big>(</big><big>)</big></dt>
<dd>Signal the task to stop and invoke the cb_stop callback.</dd></dl>

</dd></dl>

<dl class="exception">
<dt id="runtime.task.TaskException">
<em class="property">exception </em><tt class="descclassname">runtime.task.</tt><tt class="descname">TaskException</tt></dt>
<dd>Bases: <tt class="xref docutils literal"><span class="pre">exceptions.Exception</span></tt></dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="#">Runtime Documentation</a><ul>
<li><a class="reference external" href="#module-runtime.boot">The <tt class="docutils literal"><span class="pre">boot</span></tt> Module</a></li>
<li><a class="reference external" href="#module-runtime.rt">The <tt class="docutils literal"><span class="pre">rt</span></tt> Module</a></li>
<li><a class="reference external" href="#module-runtime.spaces">The <tt class="docutils literal"><span class="pre">spaces</span></tt> Module</a></li>
<li><a class="reference external" href="#module-runtime.task">The <tt class="docutils literal"><span class="pre">task</span></tt> Module</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="package.html"
                                  title="previous chapter">Package Documentation</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="services.html"
                                  title="next chapter">Services Documentation</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/runtime.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="services.html" title="Services Documentation"
             >next</a> |</li>
        <li class="right" >
          <a href="package.html" title="Package Documentation"
             >previous</a> |</li>
        <li><a href="index.html">Index</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright .
      Last updated on Jan 15, 2010.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
    </div>
  </body>
</html>